Integration Guide Kassow Robots

Note: We strongly recommend that you read the Robot communication overview before this integration guide.

Contents

• 1 Prerequisites

• 2 Robot controller setup

  • 2.1 Network configuration

  • 2.2 Copying the CBun and example programs to the controller

  • 2.3 Installing the Photoneo Bin Picking Studio CBun

  • 2.4 Configuring and activating the Bin Picking Studio device

  • 2.5 Robot State Server and visualization of the robot pose

  • 2.6 Tool (TCP) and payload setup

• 3 Robot module

  • 3.1 Connection to the Photoneo vision controller

  • 3.2 Request list

  • 3.3 The bin picking sequence

  • 3.4 Speed and blending parametrization

  • 3.5 Trajectory and object data functions

  • 3.6 Example programs

  • 3.7 Info data

  • 3.8 Error codes

• 4 Runtime

  • 4.1 Loading an example program

  • 4.2 Program structure

  • 4.3 Gripper commands

  • 4.4 Teaching the robot poses

  • 4.5 Calibration

  • 4.6 Runtime prerequisites

  • 4.7 Running the BPS_Main_Basic program

• 5 Troubleshooting

• 6 Version and brand ID

• 7 Migration

• 8 Contact information

1 Prerequisites

The Photoneo Bin Picking Studio (BPS) module for Kassow Robots is a Capability Bundle (CBun). A CBun is a binary extension that you install on the robot controller. It adds the Bin Picking Studio commands directly to the program editor on the teach pendant. This CBun is built for the FireFly controller software (packages FireFly.5 to FireFly.7.x).

Note: Controllers with HagenHevany (software package 8.x) need a separate CBun build. This guide does not cover HagenHevany.

You need:

• A Kassow Robots 7-axis robot with a Kassow Robots controller

• Controller software package FireFly.5 to FireFly.7.x

• A free Ethernet interface on the robot controller for the connection to the Photoneo vision controller

• A USB stick (or network share) to transfer the .cbun file and the example programs to the controller

• A Photoneo vision controller with a Bin Picking Studio server that supports the 1.12.0 communication protocol

• A Bin Picking Studio solution with at least one calibrated vision system, a configured environment and a configured grasping method

• A MotionCam-3D for the dynamic MultiView (Instant Meshing) example. All other examples work with any supported Photoneo 3D sensor

To check the installed software package, go to Menu → Settings → About on the teach pendant:

Note: In the handshake, the CBun identifies itself to the Bin Picking Studio server as KASSOW_ROBOTS/1.12.0XXXX. The CBun sends the same 24-byte brand ID on the Action Request link and on the Robot State Server link. The vision controller selects the matching protocol features based on this string. For this reason, you need a Bin Picking Studio server that supports the 1.12.0 protocol.

For general information on CBuns (how to manage them from the teach pendant, the basic interfaces and the control items), see the Kassow Robots Software Manual.

The Photoneo Bin Picking Studio delivery contains one CBun file and a set of example programs:

Core file: photoneo_bin_picking_studio.cbun

Example programs: BPS_Main_Basic.kr2 BPS_Main_Basic_Hand_Eye.kr2 BPS_Main_Basic_Comm_Check.kr2 BPS_Main_Basic_Get_Status.kr2 BPS_Main_Basic_Change_BBox.kr2 BPS_Main_Basic_Change_Env.kr2 BPS_Main_Basic_Change_Sol.kr2 BPS_Main_Basic_Multi_VS.kr2 BPS_Main_Basic_Reuse_Scan.kr2 BPS_Main_Basic_Multiview_Static.kr2 BPS_Main_Basic_Multiview_Dynamic.kr2 BPS_Get_Object_Pose.kr2 BPS_Calibration.kr2 BPS_Calibration_Hand_Eye.kr2

2 Robot controller setup

2.1 Network configuration

The Bin Picking Studio CBun uses two TCP connections:

• An outgoing client connection from the robot controller to the Action Request Server on the Photoneo vision controller (default port 11003). The CBun sends all requests described in section 3.2 over this link.

• An incoming connection to the Robot State Server. The CBun starts this server on the robot controller, and it listens on port 11004. The vision controller connects to it and receives the live robot joint positions and flange pose - see section 2.5.

For this reason, both devices must be reachable on the same subnet, and traffic must be allowed in both directions. This guide uses these addresses:

• Vision controller IPv4 address: 192.168.1.1 / 24

• Robot controller IPv4 address: 192.168.1.2 / 24

Configure the Ethernet interface of the robot controller on the teach pendant under Workcell, Interfaces, ethnet. Set Configuration Type to Static IP, enter the address and netmask, then press Re-Activate. See the Kassow Robots Software Manual for the exact procedure for your software version:

Then set the matching addresses on the Network page of the Photoneo vision controller:

NOTE: The subnet mask 255.255.255.0 is the same as a 24-bit subnet mask. See this table for more combinations.

To ping the Kassow robot controller from the Photoneo vision controller, use the Test Connection button on the Network page of the vision controller:

2.2 Copying the CBun and example programs to the controller

Use a USB stick to transfer the Robot module files to the robot controller. Copy the delivered folder structure to the root of the stick and insert the stick into the USB port of the teach pendant. The file browsers used later in this guide expect this layout:

• usb0 → Kassow → BPS → CBun → photoneo_bin_picking_studio.cbun

• usb0 → Kassow → BPS → Example Programs → *.kr2

Note: Install the CBun file only once per controller. Load the example programs one by one from the Program → Open dialog. After the first save, the controller keeps them in its program storage.

2.3 Installing the Photoneo Bin Picking Studio CBun

Open the main menu with the three-dot icon in the upper right corner of the teach pendant and select Settings → CBuns:

The CBuns page lists all Capability Bundles installed on the controller. Use the plus (+) button in the upper left corner to install a new one. The minus (−) button uninstalls the CBun selected in the list.

Go to the CBun folder on the USB stick and select photoneo_bin_picking_studio:

The installation dialog shows the bundle metadata. Check that the author is Kassow Robots and that the version is 1.12.0, then click Install:

After the installation, the Photoneo Bin Picking Studio bundle appears in the list on the left. Select it to see the bundle details and the device classes it provides. Here, it provides one class named Bin Picking Studio. Use the plus (+) button on the right of the Bin Picking Studio row to add a Bin Picking Studio device to the workcell:

2.4 Configuring and activating the Bin Picking Studio device

When you add the device, its configuration page opens. The NAME field contains the instance name. The program tree shows this name (default BINPCK) as the prefix of every Bin Picking Studio command. On the CONFIG tab, enter the connection parameters:

• BIN PICKING STUDIO IP ADDRESS - the IPv4 address of the Photoneo vision controller (192.168.1.1 in this guide)

• PORT - the Action Request Server port, 11003 by default

Press Activate to open the connection. When the device is active, the warning triangle next to the CONFIG tab changes to a green check mark, and the Deactivate button becomes available:

Note: The device configuration is part of the workcell, not of the program. Save the workcell (Menu → Workcell → Save) after you add or change the Bin Picking Studio device.

2.5 Robot State Server and visualization of the robot pose

Bin Picking Studio needs a continuous stream of the robot state. It uses the joint values to visualize the robot and to keep the collision environment up to date. It needs the Cartesian flange pose for calibration and for all hand-eye scan requests.

On other robot platforms, this needs a second background task that you configure separately. On Kassow Robots, you do not need to configure anything. The CBun starts the Robot State Server when you activate the Bin Picking Studio device and stops it when you deactivate the device. The server streams at approximately 10 Hz:

• All 7 joint positions [rad]

• The flange-center pose in the world frame: X, Y, Z [mm] and W, P, R [rad]

The server listens on port 11004 of the robot controller and accepts one vision controller client at a time.

Note: The reported Cartesian pose is the bare flange (flange to world). It does not depend on any TCP configured in the program. For this reason, calibration and hand-eye scan requests need no tool switching on Kassow - see section 2.6.

When the vision controller connects to the Robot State Server, the Environment page of the solution shows the live robot pose:

You can visually check that the robot reports the correct zeroed tool pose. Start Calibration, switch from the Texture tab to the Verification tab and enable Tool Pose (robot controller) in the Axis menu. The frame marker must be centered on the flange, with the Z axis along the flange normal. It must be identical to the Tool0 (robot model) frame:

Note: If the Robot State Server row on the Deployment page stays disconnected, check that the Bin Picking Studio device is active on the teach pendant. Also check that the vision controller can reach port 11004 of the robot controller.

2.6 Tool (TCP) and payload setup

Bin Picking Studio works with a zeroed tool. It compensates for the tool geometry internally during the trajectory calculation and returns a joint-space trajectory to the robot. For this reason, the TCP configured in the program has no effect on the picking trajectories executed by pho_pick.

You must still configure the tool frame and the payload, because:

• The payload is always important. The controller uses it for dynamic and safety calculations. A wrong payload causes protective stops or lower path accuracy.

• The robot program executes all its own motions with the configured tool frame. These are the approach and placing moves, and every motion in the BPS_Get_Object_Pose example.

In this tutorial, the example programs use a TCP pose variable named tcp_init and a payload variable named load_init. Before you run the robot programs, set both to match the physical gripper. It is best to do this before you touch up the robot poses.

The example programs set the tool and the payload in the first two instructions of Sequence 1:

• SET TCP = tcp_init

• SET LOAD2 = load_init

Select the tcp_init variable in the variable bar at the bottom of the screen to edit the tool frame:

Do the same for load_init to enter the mass, center of gravity and inertia of the gripper:

Note: pho_calib_add always reads the current flange-center pose (flange to world), so it does not depend on the configured TCP. Hand-eye scan requests work the same way. You do not need to switch tools around the vision requests, but the picking and placing motions must use the real tool frame.

3 Robot module

Note: We strongly recommend that you read the Photoneo robotic API before this section.

3.1 Connection to the Photoneo vision controller

The CBun opens the connection to the Action Request Server on the vision controller when the Bin Picking Studio device is activated. You can activate it manually on the device CONFIG page (section 2.4), or it activates automatically when the workcell is loaded. Set the BIN PICKING STUDIO IP ADDRESS field to the IP address of your vision controller. In this tutorial, it is 192.168.1.1.

The robot can send requests to the vision controller only after the connection is open. The green CONNECTED indicators on the Deployment page of Bin Picking Studio show a successful connection. Both the Action Request Client (Robot) and the Robot State Server must change to CONNECTED:

On the robot side, the green check mark on the CONFIG tab of the Bin Picking Studio device shows the connection state. You can also check the link from the program at any time with the pho_req_comm_check command. It returns response code 0 when the connection is alive - see the BPS_Main_Basic_Comm_Check example program.

3.2 Request list

This section describes the API calls of the Robot module. Insert these commands into the program tree from the CBuns tab of the command palette. They are for high-level control of the bin picking application.

Note: The ID column lists the request ID sent over the Photoneo communication protocol (see Action requests). pho_req_scan sends request 1, and pho_wait_scan reads its response. pho_req_traj sends request 2, and pho_recv_traj reads its response. pho_pick is a local command. It executes the received trajectory and sends no request to the vision system.

Request	ID	CBun command	Input	Populates
Initialize	4	pho_init	Vision System Id Start Pose End Pose	Response Code
Scan	1	pho_req_scan	Vision System Id	—
Wait for Scan		pho_wait_scan	None	Response Code
Trigger Scan (MultiView)	28	pho_req_capture	Vision System Id Scan Type (Extrinsic / Hand-eye)	Response Code
Reuse Scan	29	pho_req_reuse_scan	Vision System Id Scan Type (Extrinsic / Hand-eye)	Response Code
Trajectory Request	2	pho_req_traj	Vision System Id	—
Trajectory Receive		pho_recv_traj	None	Response Code Trajectory buffer, operation list, gripper commands, gripping point ID, object dimensions and pick-allowed flag. Read them with the pho_fce_* functions (section 3.5)
Execute Pick	local	pho_pick	Fly-by Joint Speed [rad/s] Fine Joint Speed [rad/s] Max Joint Acceleration [rad/s^2] Segment 1..10 Speed [%] (all optional)	Response Code
Pick Failed	7	pho_send_pick_failed	Vision System Id	Response Code
Bin Locator	3	pho_req_bin_locator	Vision System Id	Response Code
Get Object Pose	8	pho_req_get_object	Vision System Id Pose Mask (Position + Orientation / Position / Orientation / None)	Detected Object Pose Response Code
Get Vision System Status	21	pho_req_get_status	Vision System Id	Localized Object Count Number Of Ready Processing State Response Code
Change Environment Scene	15	pho_change_env	State Id	Response Code
Change Bounding Box	32	pho_change_bbox	Vision System Id Bounding Box Id	Response Code
Calibration Start	25	pho_calib_start	Solution Id Vision System Id	Response Code
Calibration Add Point	5	pho_calib_add	None (the current flange pose is read automatically)	Response Code
Calibration Save	27	pho_calib_save	None	Calibration Accuracy [µm] Calibration Matrix (RobotPose) Response Code
Calibration Stop	26	pho_calib_stop	None	Response Code
Change Solution	9	pho_change_sol	Solution Id	Response Code
Start Solution	10	pho_req_start_sol	Solution Id	Response Code
Stop Solution	11	pho_req_stop_sol	None	Response Code
Get Running Solution	12	pho_req_get_run_sol	None	Solution Id Response Code
Get Available Solutions	13	pho_req_get_avail_sol	None	Solution Id Array Response Code
Comm Check	100	pho_req_comm_check	None	Response Code

Note: pho_req_scan + pho_wait_scan is the only way to scan. pho_req_scan sends the request and returns immediately. With a hand-eye sensor, keep the robot still until the scan response arrives. With an extrinsic sensor, the robot can move in the meantime if it stays out of the scanned scene. The only exception is dynamic MultiView, where the sensor scans while the robot moves. pho_wait_scan waits until the result arrives. Only one pho_req_scan can be pending at a time. Never send a second one before you collect the result with pho_wait_scan. The trajectory works the same way: pho_req_traj sends the request, and pho_recv_traj collects the planned trajectory and its result code.

Note: pho_req_scan sends only the Vision System Id. For a hand-eye vision system, the vision controller takes the robot pose at the moment of the scan from the Robot State Server (section 2.5). For this reason, there is no Scan Type to select. Only the MultiView requests pho_req_capture and pho_req_reuse_scan still have the Scan Type (Extrinsic / Hand-eye) selector.

Note: Every command except pho_req_scan has an optional Response Code output parameter. (pho_wait_scan returns the result of pho_req_scan, and pho_recv_traj returns the result of pho_req_traj.) If the parameter is unbound and the server returns a non-zero code, the CBun raises a program error and the program stops. If the parameter is bound to a program variable, the CBun writes the code there and the program continues. The example programs do this, so that they can react to the code in the program.

Note: Vision System Id, Bounding Box Id, State Id and Solution Id are constant parameters. They take a value that you type into the Options panel, not a program variable. To switch between two IDs, you need two separate calls. For this reason, the switching examples write out each branch instead of looping over an ID variable.

3.3 The bin picking sequence

A complete bin picking cycle has five steps:

• pho_init - once per vision system, before the first scan. The joint configurations of the taught Start and End poses (.conf.j1 .. .conf.j7) are the bounds of every trajectory that Bin Picking Studio plans.

• pho_req_scan + pho_wait_scan - start the scan, localization and path planning, and wait for the result.

• pho_req_traj - request the trajectory for the next available object.

• pho_recv_traj - receive the planned trajectory.

• pho_pick - execute the trajectory.

pho_pick replaces the pho_bin_picking procedure of other Photoneo Robot modules. The CBun executes the motion itself. One call runs every trajectory segment and performs every gripper operation on the way. It uses the gripper outputs configured on the BINPCK device (protocol, DIO number, value and settle time for each command). The robot program never sees or sends a gripper command. The commands are the ones configured on the Grasping method page of the solution:

Gripper Command	Meaning	What pho_pick does
1	Attach	Writes the Gripper Attach output configured on the BINPCK device (DIO number and value) and waits for the configured settle time.
2	Detach	Writes the Gripper Detach output configured on the BINPCK device. It can use a different DIO number than Attach.
3, 4, 5	User 1, User 2, User 3	Optional auxiliary operations (blow-off, second vacuum zone, …), configured on the Grasping method page of the solution. Each one has its own output configuration on the device.

Remember two things about pho_pick:

• Each trajectory can run only once. When pho_pick returns, it discards the received trajectory, so an old trajectory can never run twice. Request and receive a new one before the next pick. If you call pho_pick without a received trajectory, it returns response code 201.

• Report a failed pick. If pho_pick returns a non-zero response code, call pho_send_pick_failed. Bin Picking Studio then updates its internal state and plans again for the remaining objects. Then move back to home and scan again.

If your program runs its own motion loop, it can still read the received trajectory point by point with the pho_fce_* functions listed in section 3.5. pho_pick is the easy way, not the only way.

3.4 Speed and blending parametrization

Bin Picking Studio supports up to 10 trajectory segments in one bin picking trajectory. The default number of segments is 4 (Start to Approach, Approach to Grasp, Grasp to Deapproach, Deapproach to End). If needed, you can configure more segments on the Grasping method page of the BPS solution.

The motion parameters are optional parameters of pho_pick. They have two layers: three cell-wide speeds, and a percentage for each segment on top of them. Every trajectory segment runs in joint space.

Layer 1 - the cell-wide speeds. They apply to the whole pick:

• Fly-by Joint Speed [rad/s] - maximum joint speed for segments that end in a blended (fly-by) point. Default 0.6 rad/s.

• Fine Joint Speed [rad/s] - maximum joint speed for segments that end in an exact (fine) point, typically the grasp itself. Default 0.3 rad/s.

• Max Joint Acceleration [rad/s^2] - maximum joint acceleration used for blending. Default 2.0 rad/s².

Bin Picking Studio marks each planned segment as fine or fly-by, and pho_pick uses the matching speed automatically. Leave the three parameters unbound to use the safe defaults, or bind them to program variables to tune the cell.

Note: The third parameter, Max Joint Acceleration, is an acceleration limit, not a blending radius. The controller calculates the blending from it.

Layer 2 - Segment 1..10 Speed [%], one optional percentage for each trajectory segment. Each percentage scales both the joint speed and the joint acceleration of its segment. A scaled segment is therefore the same path in slow motion, not a path with different blending. This is the per-segment array of the other Photoneo Robot modules. The segment numbers are the same as the ABB index in pho_speeddata{trajectory_ID}, so you can reuse an existing configuration directly. With the default 4-segment grasping method:

• Segment 1 Speed [%] - Start to Approach, the transfer into the bin.

• Segment 2 Speed [%] - Approach to Grasp. This is usually the segment to slow down. 25-50 % is a typical starting value.

• Segment 3 Speed [%] - Grasp to Deapproach, lifting the picked part out.

• Segment 4 Speed [%] - Deapproach to End, the transfer towards the place pose.

The rules are tolerant on purpose, so a partly configured program still runs the way it was tested:

• Unbound, or bound to a variable that is still 0, means 100 %, that is, exactly the layer 1 speeds. You do not need to fill in anything to keep the current behavior.

• Values are limited to 1..100 %. A percentage can only slow a segment down. It can never go above the layer 1 speeds, so a typing error such as 1000 cannot make the robot faster. To run faster, increase the Fly-by / Fine Joint Speed instead.

• Segments after 10 (Bin Picking Studio does not plan them) run unscaled.

• pho_pick reads the percentages once when it starts. If you change a bound variable during the pick, the change takes effect only at the next pick.

These are Number parameters. You bind each one to a program variable instead of typing a value. Declare a Number variable, Set it once near the top of the program and bind it to the segment. For example, to scale only the grasp segment, you need one variable and one Set instruction. Declare a Number called grasp_pct, add Set grasp_pct = 30 before the picking loop and bind it to Segment 2 Speed [%] in the Options panel of pho_pick. Leave all other segments unbound. They keep running at the full layer 1 speed.

For the first commissioning run, leave every parameter unbound. Use the Master Speed slider on the teach pendant to slow down the whole program - see section 4.7. Use the per-segment percentages later, when the pick works from start to end and you want a shorter cycle time. First increase the layer 1 speeds until the transfers are as fast as the cell allows. Then slow down the grasp segment with its percentage.

3.5 Trajectory and object data functions

In addition to the program commands above, the CBun provides value functions. You can use them directly in expressions, for example in an IF or LOOP condition or on the right side of an assignment. You do not need a separate program step. The trajectory functions read the data received by the last pho_recv_traj:

Function	Input	Returns
pho_fce_get_num_ops	None	Number - number of operations in the trajectory received by the last pho_recv_traj
pho_fce_get_op_type	Operation Index	Number - operation type of the given operation (move trajectory or gripper command)
pho_fce_get_traj_size	Trajectory Index	Number - number of points in the given trajectory
pho_fce_get_num_joints	Trajectory Index	Number - joints per point as sent by Bin Picking Studio (7 for a Kassow arm)
pho_fce_is_traj_fine	Trajectory Index	Number - 1 if the trajectory ends with a fine (exact) target, 0 otherwise
pho_fce_get_joint	Trajectory Index Point Index Joint Index	Number - single joint angle of the given trajectory point [deg]
pho_fce_get_gripper_cmd	Gripper Index	Number - gripper command of the given gripper operation
pho_fce_is_pick_allowed	None	Number - 1 if a trajectory has been received and not executed yet, 0 otherwise
pho_fce_get_gripping_point_id	None	Number - gripping point ID of the object in the last received trajectory
pho_fce_get_dim_x	None	Number - X dimension of the object in the last received trajectory [mm]
pho_fce_get_dim_y	None	Number - Y dimension of the object in the last received trajectory [mm]
pho_fce_get_dim_rot	None	Number - Z rotation of the object in the last received trajectory [mrad]
pho_fce_get_object_pose	None	RobotPose - Cartesian pose of the object in the trajectory received by the last pho_recv_traj
pho_fce_get_num_ready	Vision System Id	Number - number of localized objects waiting for processing
pho_fce_get_loc_count	Vision System Id	Number - total number of detected objects, including rejected ones
pho_fce_get_proc_state	Vision System Id	Number - 0 when processing is complete, 1 while recognition is running
pho_fce_get_run_sol	None	Number - ID of the currently deployed solution

3.6 Example programs

The Photoneo Kassow module includes several example programs. They show how to use the requests listed in section 3.2 for different use cases:

Example program	Description
BPS_Main_Basic	The basic bin picking template - start here. It shows the complete workflow. pho_init sets the bounds of the planning volume with the joint configurations of the taught Start and End poses. pho_req_scan / pho_wait_scan start the scan, localization and path planning. pho_req_traj / pho_recv_traj get the planned trajectory, and pho_pick executes it segment by segment. The program starts the next scan before the placing motion. The localization and planning of the next object then run during the placing motion, and the cycle time is shorter. Every request writes its result into a status variable, so the program can react to it instead of stopping. NOTE: Make sure that bin_picking_start and bin_picking_end are taught correctly. They define the volume in which Bin Picking Studio plans.
BPS_Main_Basic_Hand_Eye	Same as BPS_Main_Basic, but for a scanner mounted on the robot flange. In every cycle, the robot moves to the taught scan_pose and stops there for pho_req_scan(1) + pho_wait_scan. The request contains only the Vision System Id. The vision controller reads the flange pose from the Robot State Server (section 2.5), so you need no pose input and no tool switching.
BPS_Main_Basic_Comm_Check	Same as BPS_Main_Basic, but the program checks the link to the vision controller with pho_req_comm_check before it enters the main loop. If the returned status is non-zero, the program shows a dialog and stops. Use this check at program start or after a reconnection.
BPS_Main_Basic_Get_Status	Same as BPS_Main_Basic, but with pho_req_get_status calls in the loop. You can call the request repeatedly in short intervals during the localization phase. It returns: Localized Object Count - number of objects localized Number Of Ready - number of objects ready for picking Processing State - 0 when processing has finished, 1 while object recognition is still running These values are often used for advanced decisions, in particular to find the best moment to start the pick procedure.
BPS_Main_Basic_Change_BBox	Same as BPS_Main_Basic, but it switches the active localization bounding box at runtime with pho_change_bbox. The robot program can switch between preconfigured scan volumes during operation, without a change of the solution in Bin Picking Studio. Each pass of the loop picks one object from one bounding box.
BPS_Main_Basic_Change_Env	Same as BPS_Main_Basic, but it switches between two environment (collision) scenes with pho_change_env. The State Id parameter selects the environment state to activate. The program initializes the vision system again after every change, because the planning environment is different.
BPS_Main_Basic_Change_Sol	Same as BPS_Main_Basic, but it switches between two solutions. At start, the program reads the deployed solution with pho_req_get_run_sol. Each pass of the loop then calls pho_change_sol(1) and picks one object, then calls pho_change_sol(2) and picks one object. pho_init follows every pho_change_sol, because a newly deployed solution must be initialized again. Set the two Solution Ids to the solutions on your vision controller. To start and stop solutions separately, use pho_req_start_sol / pho_req_stop_sol in the same way.
BPS_Main_Basic_Multi_VS	Same as BPS_Main_Basic, but it switches between two vision systems. The Vision System Id parameter of every request is essential in this setup. It selects the vision system to initialize, trigger or query. Each vision system is initialized with its own Start and End poses.
BPS_Main_Basic_Reuse_Scan	Same as the BPS_Main_Basic_Multi_VS example, but it adds pho_req_reuse_scan. This request is useful when the scene has not changed since the last scan, but the localization must run again with a different configuration. For example, it searches for a different object or uses a different bounding box or different settings. Procedure: do a regular scan for VS1 to capture the scene. Then use pho_req_reuse_scan for VS2 to reuse the image data from VS1. This repeats the localization with a different configuration without new data.
BPS_Main_Basic_Multiview_Static	Static MultiView (meshing) example. It shows how to stitch several scans before the localization starts. This is useful for complex scenes or large objects. It uses a static approach: the robot stops at each scanning position to trigger and capture a scan. Procedure: move through all scanning poses (scan_pose_1 - scan_pose_3) and call pho_req_capture in each of them. When the capture sequence is complete, start the localization with pho_req_scan(1) and collect the result with pho_wait_scan. After a capture sequence, this request does not do a real scan and emits no light. It only starts localization and planning on the collected data. Scan limit: keep the total number of scans below 10 for the best system performance.
BPS_Main_Basic_Multiview_Dynamic	Dynamic MultiView example that shows Photoneo Instant Meshing. It uses the MotionCam-3D Parallel Structured Light technology to capture several scans while the robot moves. It collects the 3D data into one point cloud without stopping. The program uses a second program sequence that runs in parallel with the motion sequence. Sequence 1 sets the meshing_on flag before the scanning trajectory and clears it at the end. Sequence 2 loops on that flag and sends pho_req_capture every meshing_gap seconds. Then pho_req_scan(1) + pho_wait_scan start the localization. Requirements: Instant Meshing needs a MotionCam-3D (standard PhoXi 3D Scanners do not support dynamic scanning). In the BPS solution, set pho_mesh_dynamic to True. The recommended value of pho_capture_gap is approximately 500 ms. Trajectory control: keep the scanning trajectory smooth and keep the bin in the field of view of the scanner, so that tracking is not lost.
BPS_Get_Object_Pose	Localization only, without Bin Picking Studio path planning. The program still initializes the vision system with pho_init. After the scan, the robot does not request a trajectory. It gets the Cartesian pose of the object with pho_req_get_object and controls all motion itself. This is useful for pick verification, slip sheet detection and conveyor picking. The system returns the raw Cartesian pose from the localization. The CAD / STL file of the object defines the origin. No gripping points and no invariance transformations are applied. NOTE: This mode does NOT provide collision-free path planning. The approach and retract motions in the example are MOVE L instructions based on the object pose. Always use MOVE L to reach a pose from the vision system. pho_req_get_object writes only the Cartesian part of the pose variable, so a MOVE J would go to the joint configuration that the variable was taught with. Pose variables written at run time (object_pose, approach_pose) must have scope shared.
BPS_Calibration	Automatic calibration procedure for a statically mounted scanner (sphere or marker pattern, Extrinsic). Requirements: you must start and confirm the first calibration of the vision system manually in Bin Picking Studio. Calibration steps: teach all 9 calibration poses (P1 - P9). To add points to the calibration table, click “Add Calibration Point” in Bin Picking Studio, or call pho_calib_add directly from the program. Calibration accuracy: as a general rule, the calibration error must stay below 3 mm. Higher errors usually mean a systematic problem in the calibration setup. Automatic recalibration (optional): after the first calibration is successful, enable automatic recalibration in the vision system settings. Then use pho_calib_start, pho_calib_add, pho_calib_save and pho_calib_stop to run the recalibration cycle. Important: the calibration object must stay where it was during the first calibration. The calibration ball stays mounted in the same place on the flange or gripper and moves with the robot. The marker pattern stays in the same place in the cell. Otherwise, the automatic recalibration fails. The program starts and ends at home_pose. After pho_calib_stop, it retracts through the taught poses P13 - P10. Reteach or delete these moves for your cell.
BPS_Calibration_Hand_Eye	The same automatic calibration procedure for a hand-eye scanner carried by the robot (marker pattern calibration). In both programs, pho_calib_add reads the flange-center pose automatically. You need no pose input, and the CBun ignores any configured TCP.

3.7 Info data

Some responses carry additional values - the Info data. The CBun has no registers. It passes the Info data to the program as outputs of the CBun commands or through the pho_fce_* functions. The values keep the unit in which they were sent.

Key	Name	Where to read it in the robot program	Unit in robot
1	Tool point invariance	not exposed	-
2	Gripping point ID	pho_fce_get_gripping_point_id (after pho_recv_traj)	index
3	Gripping point invariance	not exposed	-
4	Dimension X	pho_fce_get_dim_x (after pho_recv_traj)	mm
5	Dimension Y	pho_fce_get_dim_y (after pho_recv_traj)	mm
6	Rotation Z	pho_fce_get_dim_rot (after pho_recv_traj)	mrad
7	Neural network label	not exposed	-
8, 9	Max Z height, Tilt	not used by BPS	-
10	Calibration accuracy	Calibration Accuracy output of pho_calib_save	µm
11	Running solution ID	Solution Id output of pho_req_get_run_sol; pho_fce_get_run_sol	integer
12	Number of localized objects	Localized Object Count output of pho_req_get_status; pho_fce_get_loc_count	integer
13	Number of ready objects	Number Of Ready output of pho_req_get_status; pho_fce_get_num_ready	integer
14	Processing state	Processing State output of pho_req_get_status; pho_fce_get_proc_state	0 / 1

Note: Keys 2 and 4-6 keep the value from the last trajectory received with pho_recv_traj. Only solutions that measure the object (AI localization) send keys 4-6. The pho_fce_get_loc_count, pho_fce_get_num_ready, pho_fce_get_proc_state and pho_fce_get_run_sol functions send their own request each time you call them. They return -1 if the request fails.

3.8 Error codes

The CBun passes the error codes from the vision controller to the program without change - see Error codes. The CBun itself also returns these codes:

Code	Name in the CBun	Meaning
1	PHO_PICK_ERR_MOTION_FAILED	pho_pick: a robot motion command or a gripper output failed during the pick.
2	-	pho_calib_start: Solution Id or Vision System Id is negative or not a whole number.
4	PHO_PICK_ERR_BAD_DATA	pho_pick: the received trajectory data are not valid or out of range. pho_req_get_object: the object pose has the wrong size (the vision controller did not accept the Kassow brand ID).
201	PHO_PICK_ERR_NO_TRAJECTORY	pho_pick: no trajectory was received, or it was already executed.
-1	-	Communication error: the CBun could not open the connection or send the request, or no response arrived before the timeout. See section 5.
-5	-	Unexpected response: the response contained neither data nor an error code.

4 Runtime

When the solution is fully configured on the vision controller, finish the remaining steps on the robot side and run the BPS_Main_Basic program.

4.1 Loading an example program

Open the main menu and select Program → Open. Go to the Example Programs folder on the USB stick and select the program that you want to run:

Click Open to confirm the dialog. Opening a program replaces the active program, so save your work first if needed:

4.2 Program structure

All main example programs have the same structure. Using BPS_Main_Basic as the reference:

• SET TCP = tcp_init and SET LOAD2 = load_init - set the tool frame and the payload (see section 2.6)

• MOVE J home - move out of the field of view of the scanner before the first request to the vision controller

• BINPCK pho_init - initialize vision system 1 with bin_picking_start and bin_picking_end

• BINPCK pho_req_scan - start the first scan from home

• LOOP - the endless pick and place loop

• BINPCK pho_wait_scan - wait until the scan, localization and path planning finish

• BINPCK pho_req_traj - request the trajectory for the next pickable object

• MOVE J bin_picking_start - move to the Start pose while Bin Picking Studio plans

• BINPCK pho_recv_traj - receive the planned trajectory

• BINPCK pho_pick - execute the whole pick in one call. The CBun controls the gripper from the gripper IO configuration of the device

• Placing - MOVE J place_up, MOVE L place_down, then BINPCK pho_req_scan for the next cycle. At the place pose, the robot is out of the view of the scanner, so localization and planning run during the release and retreat

• SET DO1 = 0, WAIT, MOVE L place_up - release and retreat

• Error paths - after a failed pick (plus BINPCK pho_send_pick_failed), a failed plan or an empty scan, first MOVE J home, and only then scan again

Select a BINPCK line in the program tree to see and edit the request parameters in the Options panel on the right. pho_init takes the Vision System Id and the two taught poses that are the bounds of the planning volume:

pho_req_scan takes only the Vision System Id. This is the same for statically mounted sensors and for sensors carried by the robot (hand-eye). pho_wait_scan takes no input and returns the Response Code of the scan.

pho_pick has the Response Code and the optional motion parameters described in section 3.4: the three cell-wide speeds and the ten per-segment percentages. There are no gripper parameters, because the CBun controls the gripper:

Scroll down in the Options panel to bind the Response Code output parameter to a status variable. Every request has this optional output, and the program must check it:

4.3 Gripper commands

Bin Picking Studio decides when a gripper operation happens. The Grasping method page of the solution defines the gripper command for each major trajectory waypoint, and pho_pick performs it inside the CBun. Configure the outputs once on the CONFIG tab of the BINPCK device. Set the output protocol (Controller DIO, Tool DIO, Fieldbus, PROFINET, EtherNet/IP) for all commands. Then set the DIO number, the value and the settle time separately for Attach, Detach and User 1..3.

Output DIO Number starts at 1, exactly like the output numbers on the teach pendant for the selected protocol. DO1 is 1, DO2 is 2, and for a fieldbus protocol it is the register bit number. DIO number 0 means that the command is not used and is skipped. A cell that only needs Attach and Detach can leave User 1..3 at 0. Output Value is the level written to the output when the command runs. The I/O page uses the same numbers for the outputs, so it is the quickest way to check which DIO to enter:

Configure Detach in the same way. It can use a different output. Its Settle Time is how long pho_pick waits after it switches the output, so that the gripper releases physically before the next segment starts:

For this reason, the pick has no gripper branches at all. The example programs switch DO1 manually only where they place the part, because the placing point is defined by the program and is outside the planned trajectory. At this point, switch the same physical output that the device uses for Detach. As an alternative, end the BPS trajectory with a Detach operation, so that pho_pick releases the part automatically:

Configure the gripper commands at a high level on the Grasping methods page in Bin Picking Studio. For example, if the Attach operation is defined at the Grasp waypoint, pho_pick writes the configured Attach output when the robot reaches the Grasp waypoint:

4.4 Teaching the robot poses

After you open BPS_Main_Basic or another template, touch up these poses before you run the program:

• home - the scanning / waiting pose. Teach it so that the robot is out of the field of view of the scanner.

• bin_picking_start and bin_picking_end - essential for all vision systems in the current solution. They define the first and last trajectory waypoints needed for the initialization, and they are the bounds of the planned trajectories. Usually they are above the center of the bin.

• bin_picking_start_2 and bin_picking_end_2 - the same pair for the second vision system in the Multi VS and Reuse Scan examples.

• place_up / place_down - the placing position. place_down is the drop point, and place_up is the retract pose above it.

• scan_pose - the scanning pose of the hand-eye example. The robot sends the scan request from this pose.

• scan_pose_1 … scan_pose_3 - the additional scanning waypoints used by the MultiView examples.

• home_pose, Calib_Start, P1 … P9 - the start / end pose, the calibration start pose and the nine calibration poses of the calibration programs. P10 … P13 are their retract path.

The poses are program variables. The variable bar at the bottom of the screen lists them. Select a pose variable to open its editor:

To touch up a pose, jog the robot to the new position with the Jogging panel on the left, in Work Space or in Joint Space:

Then open the pose variable, press Define Pose and click Define to confirm. The dialog shows the pose calculated from the current TCP and joint configuration, transformed into the selected reference pose:

Note: Kassow robots have 7 joints, so a Cartesian pose does not define one unique arm posture. The joint configuration stored with the pose (J1 - J7) solves this redundancy. This is important for bin picking for two reasons. First, always teach poses by jogging the real robot, not by typing coordinates. Second, pho_init sends this joint configuration to Bin Picking Studio as the bounds of the planning volume.

Edit the motion parameters (trajectory type, blend point and speed) of every MOVE instruction of the program in the same Options panel. The trajectory type and blend point are at the top, and the maximum velocity and blend acceleration are below them. These settings have no effect on the motions inside pho_pick. Set those motions as described in section 3.4:

4.5 Calibration

Bin Picking Studio has 2 calibration methods:

• Sphere calibration - for statically mounted sensors

• Marker pattern calibration - for sensors carried by the robot (hand-eye)

Both methods need captures of a calibration object from 9 poses with enough variation in the tool pose data. On Kassow Robots, the robot always sends the bare flange pose in the world frame to the vision controller (section 2.5). You do not need to zero any tool or reference frame manually. However, the poses must still differ in orientation, not only in position.

You can calibrate without the calibration programs of the Kassow module. Start Calibration in Bin Picking Studio, jog the robot from point to point and add the points manually in Bin Picking Studio. However, for production setups that need recalibration, we recommend that you record the calibration points in the program. Make sure that the motion between these poses is collision-free.

The Kassow module provides two programs for automatic calibration:

• BPS_Calibration - calibration procedure for a statically mounted sensor

• BPS_Calibration_Hand_Eye - the same procedure for a hand-eye sensor carried by the robot

Both programs move the robot through the taught poses P1 - P9 and call pho_calib_add in each pose. At the end, they call pho_calib_save and pho_calib_stop. In this way, they recalibrate automatically, without any action in Bin Picking Studio. The procedure starts with pho_calib_start, which takes the solution and the vision system to calibrate:

pho_calib_save also returns the Calibration Accuracy [µm] and the resulting Calibration Matrix, so the program can log or check them:

In general, the calibration error must be below 3 mm (a Calibration Accuracy below 3000 µm). On the Verification tab, check that the point cloud matches the robot body and the gripper exactly. Investigate any difference, because it can cause a collision. The most common causes are wrong tool frame values, wrong gripper model orientation, wrong robot model, encoder zeroing and an unstable robot base.

4.6 Runtime prerequisites

Do a final check before you run the bin picking application from the robot side. Make sure that:

• the Bin Picking Studio solution is correctly configured on the vision controller, including the environment and the grasping method,

• the network setup on the robot side is complete, the Bin Picking Studio device is active and the Robot State Server shows CONNECTED,

• all vision systems in the solution are calibrated,

• the tool frame (tcp_init) and the payload (load_init) match the physical gripper,

• the Start and End poses for all vision systems are touched up,

• all local poses in the main program are touched up correctly,

• the gripper commands are ready and work.

4.7 Running the BPS_Main_Basic program

Deploy your solution on the vision controller. The Action Request Client (Robot) status on the Deployment page shows DISCONNECTED until you activate the Bin Picking Studio device on the robot side:

NOTE: We strongly recommend that you set the Master Speed to a low value, for example 25%, before you run the program for the first time. The Master Speed slider is in the lower left corner of the teach pendant in Program Mode.

Switch to Program Mode and press Play. The first motion instruction moves to the home pose, so the controller asks for an interactive move to it. Press and hold the button until the robot reaches the target pose. Release it at any time to stop the movement:

When the robot reaches the pose, the dialog shows a green check. Press Continue to give control back to the program. The program then continues automatically. The sensor captures the first scan, the localization finds the objects and the path planning calculates the trajectory for the first object. The program tree highlights the instruction that is running:

If there is a pickable object in the scene and the robot controller has received the trajectory for it, the robot starts to move to the first object.

If everything looks correct, keep moving the robot to the first target and check that the path is correct. If the robot stops too far from the object or pushes it too deep, make the changes on the Tool Point or Gripping Point pages in Bin Picking Studio, not in the robot program.

If the trajectories look correct, set up your own placing routine. Tune the pho_pick speeds if needed (section 3.4), and slowly increase the Master Speed back to 100%. Tune in this order: first increase the two cell-wide joint speeds until the transfer segments are as fast as the cell allows. Then slow down single segments with their Segment N Speed [%] percentage. Usually, only the grasp segment needs this.

Congratulations, you have successfully deployed the Photoneo Bin Picking Studio interface for Kassow Robots. You can now continue to improve your application. Use the Kassow BPS 1.12.0 Quick Reference workbook (delivered with this guide) and the example programs as your guides.

5 Troubleshooting

Errors returned by the vision controller. If the Response Code of a command is bound to a program variable, the CBun writes the code there and the program continues. Check the code after every request, as the example programs do. If the Response Code is unbound, a non-zero code stops the program, and the teach pendant shows the error description. See Error codes for the meaning of each code.

Communication errors. If the connection is lost, a request cannot be sent or no response arrives in time, the command fails with code -1. The program then always stops, even if the Response Code is bound. The CBun waits for a response for:

• 30 s - pho_init, pho_req_scan / pho_wait_scan, pho_req_traj / pho_recv_traj, pho_calib_add, pho_req_get_object, pho_req_bin_locator, pho_req_capture, pho_req_reuse_scan, pho_req_get_run_sol, pho_req_get_avail_sol

• 20 s - pho_calib_start, pho_calib_save, pho_calib_stop, pho_change_sol, pho_req_start_sol, pho_req_stop_sol

• 3 s - pho_req_get_status

• 5 s - all other requests

Reconnecting. The CBun opens the connection to the vision controller only when the Bin Picking Studio device is activated. It does not reconnect automatically. After a restart of the vision controller or a network failure, deactivate and activate the device on the CONFIG tab (section 2.4). If the activation fails, check the IP address and port, and use the Test Connection button on the Network page of the vision controller.

Robot State Server not connected. See the note in section 2.5. Without the Robot State Server, hand-eye scans and calibration do not work.

Program does not load. A .kr2 program saved with an older version of the CBun may not load with this version, because the set of commands is different (see section 7). Create the BINPCK steps again, or start from the delivered example programs.

6 Version and brand ID

Robot module version	1.12.0 (shown in the CBun installation dialog, section 2.3)
CBun file	photoneo_bin_picking_studio.cbun
Controller software	FireFly.5 to FireFly.7.x
Brand ID	KASSOW_ROBOTS/1.12.0XXXX (24 bytes, sent on the Action Request link, port 11003, and on the Robot State Server link, port 11004)

See the Robot module support matrix for the supported Bin Picking Studio versions.

7 Migration

For the general changes between BPS 1.11 and BPS 1.12, see Migration from BPS 1.11.x to BPS 1.12.x. Kassow-specific changes:

• All commands and functions were renamed to the pho_* convention (for example scanStart → pho_req_scan, scanGetResult → pho_wait_scan, requestTrajectory → pho_req_traj, receiveTrajectory → pho_recv_traj, getObject → pho_req_get_object).

• pho_init takes the taught Start Pose / End Pose instead of two joint arrays. It sends all 7 joints.

• The blocking scan command (previously scan) was removed - use pho_req_scan + pho_wait_scan. pho_req_scan no longer has a Scan Type parameter.

• The separate object pose command (previously requestObjectPose) and the multi-object command (previously getObjects) were removed - use pho_req_get_object. pho_fce_get_object_pose now returns the object pose from the last received trajectory.

• pho_pick executes the received trajectory and the gripper operations inside the CBun. Optional per-segment speed percentages were added.

You must create programs saved with an older CBun again with the new commands.

8 Contact information

Headquarters: Zebra Technologies Slovakia s.r.o. Plynárenská 6 821 09 Bratislava, Slovakia

Technical support Contact us at the Help Center. Visit the Photoneo support pages at www.photoneo.com/support. Orders and inquiries: photoneo-sales@zebra.com photoneo-sales-us@zebra.com